@RCheesley thanks so much for the suggestion! I'll apply them soon and let you know when they're ready. 👍🏼

In the meantime, I'd like to explain why I do below details across our docs:

1. I don't apply admonitions to notes, warnings, etc. that are part of ordered and unordered list.
2. I'm using <details> and <summary> tags

Admonitions

Applying GitHub admonitions for notes, tip, or warnings as part of the list does:

• Break the indentation and flow
• The point above, combine with many images that we use in the guidelines, make the whole guidelines not easy to read and understand

Here are some screenshot of examples:

1. Admonition as part of unordered list

As you can see, the admonition is out of the flow.

2. Admonition as part of ordered list

Image 1

Just like the example in unordered list, the admonition is out of the flow.

Image 2

After the admonition, all instructions are still belong to point 4. But the indentation follows the admonition instead of the point. This can cause confusions.

Image 3

For this one, I indent the admonition just like we indent a paragraph that's part of a point. The indentation works great, but the admonition breaks.

The <details> and <summary> tags

I'm using these tags to create a collapsible section because these sections are meant for folks who need to troubleshoot codespaces and want to know a nice-to-know info about how to maximize free tier of Codespaces.

We can make these as sub-sections. But this will make the contributing guidelines too long.

Another solution that I can come up with is to create a new file dedicated for these tip and troubleshooting.

Testing repo

I created a test repo for your consideration: https://github.com/adiati98/test-github-markdown-for-mautic/blob/main/.github/apply-suggestions-no-html-admonitions-in-list.md.

In this repo, I applied below suggestions:

• Added admonitions
• Remove all HTML and make the file pure Markdown. This included removing the <details> and <summary> tags, and make them sub-sections.

Just let me know if you have better solutions or we would still apply the suggestions. TIA! ✨

@RCheesley TIL that we can wrap one point of order list with vale and it doesn't break it as in RST. 💡

Here's the preview for this PR:
https://github.com/adiati98/test-github-markdown-for-mautic/blob/main/.github/dev-docs-with-skip-vale.md

@RCheesley can you please add @adiati98 to docs at all contributors? TIA! ✨

@all-contributors please add @adiati98 for docs

@RCheesley

@adiati98 already contributed before to doc